.\" Copyright (c) 2012-2018 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd January 1, 2012
.Dt AG_KEYBOARD 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.5.0
.Sh NAME
.Nm AG_Keyboard
.Nd agar direct keyboard interface
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
The
.Nm
interface provides a direct interface to keyboard status.
This manual page also documents a few utility routines for dealing
with Agar keyboard symbols.
The
.Nm
object itself is registered and accessed through the
.Xr AG_Driver 3
interface.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_InputDevice 3 ->
.Nm .
.Sh WIDGET INTERFACE
.nr nS 1
.Ft "const char *"
.Fn AG_LookupKeyName "AG_KeySym sym"
.Pp
.Ft "AG_KeySym"
.Fn AG_LookupKeySym "const char *name"
.Pp
.Ft "int *"
.Fn AG_GetKeyState "AG_Widget *widget"
.Pp
.Ft "int"
.Fn AG_GetKeyCount "AG_Widget *widget"
.Pp
.Ft "void"
.Fn AG_SetKeyState "AG_Widget *widget" "int *keyState"
.Pp
.Ft "Uint"
.Fn AG_GetModState "AG_Widget *widget"
.Pp
.Ft "void"
.Fn AG_SetModState "AG_Widget *widget" "Uint modState"
.Pp
.Ft "int"
.Fn AG_CompareKeyMods "Uint modState" "const char *flags"
.Pp
.nr nS 0
The
.Fn AG_LookupKeyName
function returns a short string describing the given
.Xr AG_KeySym 3
value (or NULL if the argument is out of range).
.Fn AG_LookupKeySym
returns a keysym value for the specified name (or
.Dv AG_KEY_NONE
if no match was found).
.Pp
The
.Fn AG_GetKeyState
function returns a pointer to an array of integers which represent the
current keyboard status.
The array has up to
.Dv AG_KEY_LAST
entries (see
.Xr AG_KeySym 3 ) .
.Fn AG_GetKeyCount
returns the number of entries in the keyboard status array.
.Pp
The
.Fn AG_SetKeyState
routine overwrites the keyboard status array with the contents of
.Fa keyState
(which should have
.Dv AG_KEY_LAST
entries).
.Pp
.Fn AG_GetModState
returns the current keyboard modifier status (see
.Xr AG_KeyMod 3 ) .
.Fn AG_SetModState
overwrites the current modifier status with the value of
.Fa modState .
.Pp
The
.Fn AG_CompareKeyMods
function compares a modifier status against a string of flags, returning
1 if any of the modifiers described by the string are active, or 0 otherwise.
No distinction is made between left and right-sided modifiers.
The string may contain "C" for CTRL, "A" for ALT, "S" for SHIFT,
and "M" for META.
.Sh INTERNAL DRIVER INTERFACE
.nr nS 1
.Ft "AG_Keyboard *"
.Fn AG_KeyboardNew "AG_Driver *drv" "const char *descr"
.Pp
.Ft "int"
.Fn AG_KeyboardUpdate "AG_Keyboard *kbd" "AG_KeyboardAction action" "AG_KeySym sym"
.Pp
.Ft "int"
.Fn AG_ProcessKey "AG_Keyboard *kbd" "AG_Window *win" "AG_KeyboardAction action" "AG_KeySym sym" "Uint32 unicode"
.Pp
.nr nS 0
The
.Fn AG_KeyboardNew
function registers a new keyboard device under the specified
.Xr AG_Driver 3 .
.Pp
When a keyboard event is received by the driver, it should call
.Fn AG_KeyboardUpdate
to update Agar's internal keyboard status as soon as the event is
received.
Typically,
.Fn AG_KeyboardUpdate
is called by the
.Fn GetNextEvent
routine of the driver (see
.Xr AG_GetNextEvent 3 ) .
.Pp
The
.Fn AG_ProcessKey
function is called to perform final processing of key press and key
release events (sending
.Sq key-up
and
.Sq key-down
events to the appropriate Agar widgets).
Typically,
.Fn AG_ProcessKey
is called from the
.Fn ProcessEvent
routine of the driver (see
.Xr AG_ProcessEvent 3 ) .
.Pp
.Fn AG_KeyboardUpdate
and
.Fn AG_ProcessKey
accept the same arguments.
.Fa action
should be
.Dv AG_KEY_PRESSED
or
.Dv AG_KEY_RELEASED .
The
.Fa sym
argument is the Agar virtual key (see
.Xr AG_KeySym 3 ) ,
and
.Fa unicode
is the Unicode character value.
Either (but not both) arguments may be undefined.
.Fa sym
may be set to
.Dv AG_KEY_NONE
if there is no corresponding Agar virtual key, and
.Fa unicode
may be set to 0 if there is no corresponding Unicode character
(as should be the case for function keys).
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_KeyMod 3 ,
.Xr AG_KeySym 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
The
.Nm
interface first appeared in Agar 1.4, and the widget interface was
first documented in Agar 1.5.0.
